Add Sphinx extension and autogen function for documenting config options#458
Add Sphinx extension and autogen function for documenting config options#458minrk merged 1 commit intoipython:masterfrom
Conversation
|
@takluyver Out of curiosity, does this supersede some prior automatic documentation systems that have been proposed, or would this compliment one? |
|
I'm not sure which systems you're referring to. In some ways it supersedes the method in traitlets to generate rst docs, but the new function produces rst that is only valid in Sphinx with the extension loaded, so it's not a drop-in replacement for the older one. |
|
I had proposed #261 some time ago, though it definitely needs to be rewritten. The goal was to update |
|
On the face of it, I think this is complementary to #261. That's focused on documenting traitlets within a Python API, for interactive inspection and for API docs. This is specifically about documenting traitlets used as application config - so the starting point is an application rather than a class, it only selects configurable traits, and it focuses on things like command line aliases. The main motivation for this is that I want to be able to link people to individual config options in our docs. |
Carreau
added
5.0-re-review
Carreau
added
5.0-major
4 participants
This is the machinery we prototyped for documenting IPython config options. By defining a simple Sphinx extension, individual config options can be linkable, cross-referenceable, and nicely searchable.
It was always my intention to move this into traitlets so we can easily use it for other Jupyter applications. I'm not aware of any problems since we started using it for IPython.